Rant: Literal User Manuals

"functionoverfashion" (functionoverfashion) 12/08/2016 at 11:20 • Filed to: rants

4

5

User manuals that only tell you what can be learned by observation are quite possibly the worst. Worse than pickles, even. Headlight switch: Use this switch to activate your headlights. Thank you Captain Obvious.

I’m working with some new (to me) software at work and the documentation is like this. I’m creating an award process where people apply, then a committee reviews the applications, and the top x number of applicants get the award. Pretty straightforward, really.

In selecting from a drop-down menu that defines a piece of the review process, I have to choose the “Routing Step Type.” I have no idea what the options mean, so I click on the ? bubble right there. Here’s the content:

[our software] supports a number of different Routing Step Types. Select the one that is most appropriate to the Routing Step you are creating.

WTF. Thank you for explaining what a drop-down menu is. Now WHAT DO THE OPTIONS ACTUALLY MEAN WITHIN THIS SPECIFIC MENU?!

So I consulted the user manual, this is literally the entire content related to this topic:

There are three different Comments and Ratings Combinations available as well – 1 combo, 2 combo, and 3 combo varieties. This style of routing step is most valuable for setting up reviewers or review committees.

Great! I’m using a review committee! But wait. STILL no explanation of what a “2 combo” variety actually is. And on the web, they clearly have updated it to allow for more, in fact, up to “18 combo” but I have no idea what I’m getting except maybe those weird round cheese-filled crackers that I remember loving in the 90's.

seriouseats.com via google image search

Adding to my confusion is the fact that the list reads like this:

1 comments and ratings combination

approve/do not approve

document upload

2 comments and ratings combination

3 comments and ratings combination

... and so on.

Is the number defining the number of questions that can be rated? Or, the number of people that can rate it? Or something else?

I tried to email support to ask about it and their own system isn’t working for submitting a ticket.

Contact the site owner? YOU are the site owner, and I’m trying to contact you.

Can I go home now?

BiTurbo228 - Dr Frankenstein of Spitfires > functionoverfashion 12/08/2016 at 11:30

1

Hey. Pickles are excellent. Don’t bring them into this.

‘Captain Obvious’ user manuals and other such guff should die a death though.

functionoverfashion > BiTurbo228 - Dr Frankenstein of Spitfires 12/08/2016 at 11:35

0

It seems common in tech, where the guy writing the manual has a deep and thorough knowledge of the product and the related terminology but no acknowledgement that others may not. So the manual says, “the filter menu lets you pick from various filters, including gingham, plaid, starchase, diamond, meatloaf, and loon. Choose the best filter for your application and click Apply.”

BiTurbo228 - Dr Frankenstein of Spitfires > functionoverfashion 12/08/2016 at 11:44

1

Yeah that’s a definite issue I’ve come across before.

What they should do, is get someone to write the user manual who has no idea whatsoever what the product is or does. Then, get them to ask the experts how to navigate it, and write down their responses.

Sounds like a recipe for the unfortunate sod getting a hammer to the head (or the expert having a brain aneurysm), but it would make for a useful manual :)

Justin Hughes > functionoverfashion 12/08/2016 at 12:09

0

I write these manuals for my day job. I agree with you 100%!!! I desperately try to avoid such circular illogic in what I write.

functionoverfashion > Justin Hughes 12/08/2016 at 12:21

0

It’s clear when they’ve been written by someone who was at least sort of paying attention....